Frontend File System Access API: vietinių failų valdymas naršyklėje

File System Access API (anksčiau žinoma kaip Native File System API arba tiesiog File System API) yra galingas interneto API rinkinys, leidžiantis interneto programoms tiesiogiai iš naršyklės sąveikauti su failais ir katalogais vartotojo vietinėje failų sistemoje. Tai atveria naujas galimybes interneto programoms, leidžiančioms atlikti užduotis, kurios anksčiau buvo prieinamos tik vietinėms programoms.

Kas yra File System Access API?

File System Access API suteikia būdą vartotojams leisti interneto programoms pasiekti jų vietinę failų sistemą. Skirtingai nuo senesnių failų įkėlimo/atsisiuntimo mechanizmų, šis API leidžia programoms tiesiogiai skaityti, rašyti ir valdyti failus bei katalogus, gavus aiškų vartotojo sutikimą. Tai siūlo sklandesnę ir labiau integruotą patirtį, ypač programoms, kurios dirba su dideliais vietinių duomenų kiekiais arba reikalauja nuolatinės saugyklos.

Pagrindinės File System Access API savybės:

• Vartotojo suteikiami leidimai: Prieiga prie failų sistemos suteikiama tik po to, kai vartotojas aiškiai patvirtina užklausą, užtikrinant vartotojo privatumą ir saugumą.
• Nuolatinė saugykla: Interneto programos gali prašyti nuolatinės saugyklos, leidžiančios joms išlaikyti prieigą prie failų ir katalogų net ir uždarius ar atnaujinus naršyklę.
• Asinchroninės operacijos: API daugiausia naudoja asinchronines operacijas, neleidžiančias vartotojo sąsajai (UI) „užšalti“ sąveikaujant su failų sistema.
• Srautais pagrįsta prieiga: Srautų palaikymas leidžia efektyviai tvarkyti didelius failus, neįkeliant viso failo į atmintį.
• Prieiga prie katalogų: Programos gali prašyti prieigos prie ištisų katalogų, leidžiančios joms valdyti kelis failus ir aplankus.
• Origin Private File System (OPFS): speciali, izoliuota failų sistemos dalis, unikali svetainės kilmei, suteikianti geresnį našumą ir saugumą specifiniams naudojimo atvejams.

File System Access API panaudojimo atvejai

File System Access API atveria platų galimybių spektrą interneto programoms. Štai keletas dažniausiai pasitaikančių panaudojimo atvejų:

1. Vietinių failų redaktoriai ir IDE

Interneto kodo redaktoriai, teksto redaktoriai ir IDE gali pasinaudoti API, kad tiesiogiai atidarytų, redaguotų ir išsaugotų failus vartotojo vietinėje failų sistemoje. Tai suteikia labiau į vietinę programą panašią patirtį, palyginti su tradicinėmis failų įkėlimo/atsisiuntimo darbo eigomis. Įsivaizduokite internetinę IDE, pavyzdžiui, VS Code, kuri tiesiogiai redaguoja jūsų projekto failus, saugomus vietoje.

2. Vaizdo ir garso įrašų redagavimo įrankiai

Vaizdo ir garso įrašų redagavimo programos gali naudoti API, kad efektyviai apdorotų didelius medijos failus, saugomus vartotojo įrenginyje. Srautais pagrįsta prieiga leidžia redaguoti failus neįkeliant viso turinio į atmintį, taip pagerinant našumą ir sumažinant atminties sąnaudas. Pavyzdžiui, internetinis nuotraukų redaktorius galėtų tiesiogiai atidaryti ir išsaugoti nuotraukas iš jūsų kompiuterio be būtinybės jas įkelti.

3. Dokumentų valdymo sistemos

Interneto dokumentų valdymo sistemos gali užtikrinti sklandžią integraciją su vartotojo vietine failų sistema, leisdamos jiems lengvai pasiekti, tvarkyti ir valdyti savo dokumentus tiesiogiai iš naršyklės. Įsivaizduokite debesų saugyklos paslaugą, leidžiančią tiesiogiai atidaryti ir redaguoti vietinius dokumentus jos interneto sąsajoje.

4. Žaidimų kūrimas

Žaidimų kūrėjai gali naudoti API žaidimų ištekliams saugoti, žaidimo eigai išsaugoti ir pasirinktiniam turiniui įkelti tiesiai iš vartotojo failų sistemos. Tai leidžia sukurti turtingesnes ir labiau įtraukiančias žaidimų patirtis internete. Įsivaizduokite internetinį žaidimą, kuris išsaugo jūsų eigą tiesiai į jūsų kompiuterį.

5. Programos, veikiančios neprisijungus

File System Access API, kartu su kitomis technologijomis, tokiomis kaip service workers, leidžia kurti interneto programas, galinčias veikti neprisijungus prie interneto. Duomenys gali būti saugomi vietoje naudojant API ir sinchronizuojami su nuotoliniu serveriu, kai ryšys atkuriamas. Tai ypač naudinga produktyvumo programoms, kurios turi veikti sklandžiai tiek prisijungus, tiek neprisijungus. Pavyzdžiui, užrašų programėlė galėtų saugoti užrašus vietoje ir sinchronizuoti juos su debesimi, kai atsiranda ryšys.

6. Duomenų apdorojimas ir analizė

Interneto programos gali pasinaudoti API, kad apdorotų ir analizuotų didelius duomenų rinkinius, saugomus vietoje. Tai ypač naudinga moksliniams tyrimams, duomenų analizei ir kitoms programoms, reikalaujančioms apdoroti didelius duomenų kiekius. Įsivaizduokite internetinį duomenų vizualizavimo įrankį, tiesiogiai apdorojantį CSV failą iš jūsų standžiojo disko.

Kaip naudoti File System Access API

File System Access API suteikia keletą funkcijų sąveikai su failų sistema. Štai pagrindinė apžvalga, kaip naudoti kai kurias pagrindines funkcijas:

1. Prieigos prie failų sistemos prašymas

Pirmas žingsnis yra paprašyti vartotojo prieigos prie failų sistemos. Tai paprastai daroma naudojant showOpenFilePicker() arba showSaveFilePicker() metodus.

showOpenFilePicker()

Metodas showOpenFilePicker() paragins vartotoją pasirinkti vieną ar kelis failus. Jis grąžina „promise“, kuris išsisprendžia su FileSystemFileHandle objektų masyvu, atstovaujančiu pasirinktus failus.

            
async function openFile() {
  try {
    const [fileHandle] = await window.showOpenFilePicker();
    const file = await fileHandle.getFile();
    const contents = await file.text();
    console.log(contents);
  } catch (err) {
    console.error(err.name, err.message);
  }
}

            

              
                Copy
              
            
          

Pavyzdžio paaiškinimas:

• `async function openFile() { ... }`: Apibrėžia asinchroninę funkciją failo atidarymo procesui valdyti.
• `const [fileHandle] = await window.showOpenFilePicker();`: Naudoja `showOpenFilePicker()`, kad parodytų failo pasirinkimo dialogą. Raktinis žodis `await` sustabdo vykdymą, kol vartotojas pasirenka failą (arba atšaukia operaciją). Rezultatas yra masyvas, kuriame yra `FileSystemFileHandle` objektai; mes išskaidome pirmąjį elementą į `fileHandle` kintamąjį.
• `const file = await fileHandle.getFile();`: Gauna `File` objektą iš `FileSystemFileHandle`. Šis `File` objektas suteikia prieigą prie failo savybių ir turinio.
• `const contents = await file.text();`: Nuskaito visą failo turinį kaip teksto eilutę, naudodamas `text()` metodą. Raktinis žodis `await` laukia, kol failo skaitymo operacija bus baigta.
• `console.log(contents);`: Išveda failo turinį į konsolę.
• `} catch (err) { ... }`: Sugeria bet kokias klaidas, kurios gali įvykti failo atidarymo ar skaitymo proceso metu. Jis išveda klaidos pavadinimą ir pranešimą į konsolę derinimo tikslais. Tai yra labai svarbu tvarkant scenarijus, kai vartotojas atšaukia failo pasirinkimą, failas yra nepasiekiamas arba kyla problemų skaitant failo turinį.

showSaveFilePicker()

Metodas showSaveFilePicker() paragins vartotoją pasirinkti vietą, kurioje norima išsaugoti failą. Jis grąžina „promise“, kuris išsisprendžia su FileSystemFileHandle objektu, atstovaujančiu pasirinktą failą.

            
async function saveFile(data) {
  try {
    const fileHandle = await window.showSaveFilePicker({
      suggestedName: 'my-file.txt',
      types: [{
        description: 'Text files',
        accept: {
          'text/plain': ['.txt'],
        },
      }],
    });
    const writable = await fileHandle.createWritable();
    await writable.write(data);
    await writable.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
}

            

              
                Copy
              
            
          

Pavyzdžio paaiškinimas:

• `async function saveFile(data) { ... }`: Apibrėžia asinchroninę funkciją `saveFile`, kuri priima `data` (turinį, kurį reikia išsaugoti) kaip argumentą.
• `const fileHandle = await window.showSaveFilePicker({ ... });`: Iškviečia `showSaveFilePicker()`, kad būtų parodytas išsaugojimo dialogas. Raktinis žodis `await` užtikrina, kad funkcija lauks vartotojo sąveikos. * `suggestedName: 'my-file.txt'` siūlo numatytąjį failo pavadinimą. * `types: [...]` nurodo failų tipų filtrus: * `description: 'Text files'` pateikia vartotojui draugišką failo tipo aprašymą. * `accept: { 'text/plain': ['.txt'] }` nurodo, kad dialogas turėtų filtruoti `.txt` failus su MIME tipu `text/plain`.
• `const writable = await fileHandle.createWritable();`: Sukuria `FileSystemWritableFileStream`, susietą su failo rankena. Šis srautas leidžia rašyti duomenis į failą.
• `await writable.write(data);`: Įrašo `data` (turinį, kurį reikia išsaugoti) į rašymo srautą.
• `await writable.close();`: Uždaro rašymo srautą, užtikrindamas, kad visi duomenys būtų įrašyti į failą ir failas būtų tinkamai užbaigtas.
• `} catch (err) { ... }`: Apima klaidų tvarkymą, kad būtų galima sugauti ir užregistruoti bet kokias klaidas, kurios gali įvykti išsaugojimo proceso metu.

2. Failo turinio skaitymas

Kai turite FileSystemFileHandle objektą, galite pasiekti failo turinį naudodami getFile() metodą. Tai grąžina File objektą, kuris suteikia metodus failo turiniui skaityti kaip tekstą, dvejetainius duomenis arba srautą.

            
async function readFileContents(fileHandle) {
  const file = await fileHandle.getFile();
  const contents = await file.text();
  return contents;
}

            

              
                Copy
              
            
          

3. Rašymas į failus

Norėdami rašyti į failą, turite sukurti FileSystemWritableFileStream objektą, naudodami FileSystemFileHandle objekto createWritable() metodą. Tada galite naudoti write() metodą duomenims rašyti į srautą, o close() metodą – srautui uždaryti ir pakeitimams išsaugoti.

            
async function writeFileContents(fileHandle, data) {
  const writable = await fileHandle.createWritable();
  await writable.write(data);
  await writable.close();
}

            

              
                Copy
              
            
          

4. Prieiga prie katalogų

File System Access API taip pat leidžia prašyti prieigos prie katalogų. Tai daroma naudojant showDirectoryPicker() metodą.

            
async function openDirectory() {
  try {
    const directoryHandle = await window.showDirectoryPicker();
    console.log('directoryHandle', directoryHandle);
    // Now you can interact with the directoryHandle to list files, create new files, etc.
  } catch (err) {
    console.error(err.name, err.message);
  }
}

            

              
                Copy
              
            
          

Kai turite FileSystemDirectoryHandle objektą, galite naudoti metodus, tokius kaip entries(), getFileHandle() ir getDirectoryHandle(), norėdami naršyti katalogo struktūroje ir pasiekti failus bei subkatalogus.

5. The Origin Private File System (OPFS)

Origin Private File System (OPFS) yra speciali, izoliuota (angl. sandboxed) failų sistemos dalis, kuri yra izoliuota pagal interneto programos kilmę. Prieiga prie failų OPFS viduje yra optimizuota našumui. Štai kaip prie jos prisijungti:

            
async function accessOPFS() {
  try {
    const root = await navigator.storage.getDirectory();
    console.log('OPFS root directory handle:', root);

    // Create a file in the OPFS
    const fileHandle = await root.getFileHandle('my-opfs-file.txt', { create: true });
    const writable = await fileHandle.createWritable();
    await writable.write('This is data in the OPFS!');
    await writable.close();

    // Read the file back
    const file = await fileHandle.getFile();
    const contents = await file.text();
    console.log('Contents from OPFS file:', contents);
  } catch (err) {
    console.error('Error accessing OPFS:', err);
  }
}

accessOPFS();

            

              
                Copy
              
            
          

Paaiškinimas:

• `navigator.storage.getDirectory()`: Gauna šakninio katalogo rankeną OPFS. Tai yra įėjimo taškas prieigai prie failų, esančių kilmės privačioje failų sistemoje.
• `root.getFileHandle('my-opfs-file.txt', { create: true })`: Gauna failo rankeną failui, pavadintam 'my-opfs-file.txt'. Parinktis `{ create: true }` užtikrina, kad failas bus sukurtas, jei jis dar neegzistuoja.
• Likusioji kodo dalis demonstruoja duomenų rašymą į failą ir jų nuskaitymą atgal, panašiai kaip ankstesniuose pavyzdžiuose.

Saugumo aspektai

File System Access API kelia naujų saugumo klausimų, kuriuos kūrėjai turi žinoti:

• Vartotojo leidimai: Visada prašykite tik būtinų leidimų ir aiškiai paaiškinkite vartotojui, kodėl jūsų programai reikia prieigos prie jo failų sistemos.
• Įvesties patvirtinimas: Išvalykite ir patvirtinkite bet kokius duomenis, nuskaitomus iš failų, kad išvengtumėte saugumo pažeidžiamumų, tokių kaip „cross-site scripting“ (XSS) ar kodo injekcijos.
• Kelio apėjimas (Path Traversal): Būkite atsargūs konstruodami failų kelius, kad išvengtumėte kelio apėjimo atakų, kai užpuolikas galėtų gauti prieigą prie failų, esančių už numatyto katalogo ribų.
• Duomenų jautrumas: Atsižvelkite į tvarkomų duomenų jautrumą ir imkitės atitinkamų priemonių jiems apsaugoti, pavyzdžiui, šifravimo ir prieigos kontrolės.
• Venkite saugoti jautrius duomenis: Jei įmanoma, venkite saugoti jautrią informaciją vartotojo failų sistemoje. Apsvarstykite galimybę naudoti naršyklės saugyklos API (pvz., IndexedDB) duomenims saugoti naršyklės izoliuotoje aplinkoje.

Naršyklių suderinamumas

Naršyklių palaikymas File System Access API vis dar tobulėja. Nors dauguma modernių naršyklių palaiko pagrindines API funkcijas, kai kurios funkcijos gali būti eksperimentinės arba reikalauti įjungti specifines vėliavėles. Prieš naudodami API gamyboje, visada patikrinkite naujausią informaciją apie naršyklių suderinamumą. Naujausią suderinamumo informaciją galite rasti tokiuose šaltiniuose kaip MDN Web Docs.

Polifilai ir atsarginiai sprendimai

Naršyklėms, kurios pilnai nepalaiko File System Access API, galite naudoti polifilus (polyfills) arba atsarginius sprendimus, kad užtikrintumėte sklandesnį veikimo pablogėjimą. Pavyzdžiui, galite naudoti tradicinį failų įkėlimo/atsisiuntimo mechanizmą kaip atsarginį sprendimą naršyklėms, kurios nepalaiko showOpenFilePicker() ar showSaveFilePicker() metodų. Taip pat apsvarstykite laipsnišką programos tobulinimą. Suteikite pagrindinį funkcionalumą be API, o tada pagerinkite patirtį naršyklėms, kurios jį palaiko.

Pavyzdys: paprasto teksto redaktoriaus kūrimas

Štai supaprastintas pavyzdys, kaip sukurti paprastą teksto redaktorių naudojant File System Access API:

            
<textarea id="editor" style="width: 100%; height: 300px;"></textarea>
<button id="openBtn">Open File</button>
<button id="saveBtn">Save File</button>

            

              
                Copy
              
            
          

            
const editor = document.getElementById('editor');
const openBtn = document.getElementById('openBtn');
const saveBtn = document.getElementById('saveBtn');

let fileHandle;

openBtn.addEventListener('click', async () => {
  try {
    [fileHandle] = await window.showOpenFilePicker();
    const file = await fileHandle.getFile();
    editor.value = await file.text();
  } catch (err) {
    console.error(err.name, err.message);
  }
});

saveBtn.addEventListener('click', async () => {
  try {
    if (!fileHandle) {
      fileHandle = await window.showSaveFilePicker();
    }
    const writable = await fileHandle.createWritable();
    await writable.write(editor.value);
    await writable.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
});

            

              
                Copy
              
            
          

Šis pavyzdys parodo, kaip atidaryti failą, parodyti jo turinį teksto lauke ir išsaugoti pakeitimus atgal į failą. Tai yra labai paprastas pavyzdys, kuriam reikėtų papildomo klaidų tvarkymo ir funkcijų realiai programai.

Geroji praktika naudojant File System Access API

• Laipsniškas tobulinimas: Kurkite savo programą taip, kad ji veiktų ir be File System Access API. Naudokite API, kad pagerintumėte vartotojo patirtį, kai ji yra prieinama.
• Pateikite aiškius paaiškinimus: Aiškiai paaiškinkite vartotojui, kodėl jūsų programai reikia prieigos prie jo failų sistemos ir ką ketinate daryti su failais.
• Sklandžiai tvarkykite klaidas: Įgyvendinkite patikimą klaidų tvarkymą, kad sklandžiai tvarkytumėte scenarijus, kai vartotojas atsisako suteikti leidimą, failas nerandamas arba kyla kitų klaidų.
• Naudokite asinchronines operacijas: Visada naudokite asinchronines operacijas, kad vartotojo sąsaja „neužšaltų“ sąveikaujant su failų sistema.
• Optimizuokite našumą: Naudokite srautais pagrįstą prieigą dideliems failams, kad pagerintumėte našumą ir sumažintumėte atminties sąnaudas.
• Gerbkite vartotojo privatumą: Atsižvelkite į vartotojo privatumą ir pasiekite tik tuos failus ir katalogus, kurie yra būtini jūsų programos veikimui.
• Kruopščiai testuokite: Kruopščiai testuokite savo programą skirtingose naršyklėse ir operacinėse sistemose, kad užtikrintumėte suderinamumą ir stabilumą.
• Apsvarstykite Origin Private File System (OPFS): Našumui kritinėms operacijoms, ypač toms, kurios susijusios su dideliais failais, apsvarstykite galimybę naudoti OPFS.

Išvada

File System Access API yra galingas įrankis, suteikiantis frontend programuotojams galimybę kurti interneto programas su išplėstomis failų sistemos galimybėmis. Leisdamas vartotojams suteikti interneto programoms prieigą prie savo vietinių failų ir katalogų, šis API atveria naujas galimybes interneto produktyvumo įrankiams, kūrybinėms programoms ir dar daugiau. Nors naršyklių palaikymas vis dar tobulėja, File System Access API yra reikšmingas žingsnis į priekį interneto programavimo evoliucijoje. Naršyklių palaikymui bręstant ir programuotojams įgyjant daugiau patirties su API, galime tikėtis pamatyti dar daugiau novatoriškų ir patrauklių interneto programų, kurios išnaudos jo galimybes.

Nepamirškite visada teikti pirmenybę vartotojo saugumui ir privatumui, naudodami File System Access API. Laikydamiesi gerosios praktikos ir atidžiai apsvarstydami saugumo pasekmes, galite sukurti interneto programas, kurios yra tiek galingos, tiek saugios.